require-directory

What is require-directory?

The require-directory npm package allows you to recursively iterate over all the files in a directory and require them. This is useful for automatically loading scripts, such as routes, models, or configurations, without having to manually require each file.

What are require-directory's main functionalities?

Recursively requiring modules in a directory

This feature allows you to require all modules in a directory and its subdirectories. The 'module' variable refers to the current module, and 'require-directory' will load all modules relative to it.

const requireDirectory = require('require-directory');
const modules = requireDirectory(module);

Whitelisting files to require

This feature allows you to specify a regular expression to filter the files to be required. In this example, only files with a '.js' extension will be required.

const requireDirectory = require('require-directory');
const modules = requireDirectory(module, {
  include: /\.js$/
});

Excluding files from being required

This feature allows you to specify a regular expression to exclude certain files from being required. In this example, files ending with '.test.js' will be ignored.

const requireDirectory = require('require-directory');
const modules = requireDirectory(module, {
  exclude: /\.test\.js$/
});

Custom handler for each required module

This feature allows you to provide a custom handler function that is called for each module that is required. In this example, if the exported module is a function, it is invoked.

const requireDirectory = require('require-directory');
const modules = requireDirectory(module, {
  visit: function (obj) {
    if (obj instanceof Function) obj();
  }
});

Other packages similar to require-directory

require-all

The 'require-all' package is similar to 'require-directory' in that it can also load all files within a directory. It provides options to filter files by a regular expression and to map the names of the keys in the returned object. It differs in its API and additional options for directory traversal and naming.

import-fresh

While 'import-fresh' is not used for bulk requiring modules, it allows you to require a module afresh, ensuring that it is not returned from the cache. This is useful for testing or when you need to reload a module's state.

glob

The 'glob' package provides pattern matching for file paths and can be used to find files in a directory that match a given pattern. It does not require the files but can be used in conjunction with 'require' to dynamically load modules that match a pattern.

README

require-directory

Recursively iterates over specified directory, require()'ing each file, and returning a nested hash structure containing those modules.

Follow me (@troygoode) on Twitter!

How To Use

Installation (via npm)

$ npm install require-directory

Usage

A common pattern in node.js is to include an index file which creates a hash of the files in its current directory. Given a directory structure like so:

• app.js
• routes/
  • index.js
  • home.js
  • auth/
    • login.js
    • logout.js
    • register.js

routes/index.js uses require-directory to build the hash (rather than doing so manually) like so:

var requireDirectory = require('require-directory');
module.exports = requireDirectory(module);

app.js references routes/index.js like any other module, but it now has a hash/tree of the exports from the ./routes/ directory:

var routes = require('./routes');

// snip

app.get('/', routes.home);
app.get('/register', routes.auth.register);
app.get('/login', routes.auth.login);
app.get('/logout', routes.auth.logout);

The routes variable above is the equivalent of this:

var routes = {
  home: require('routes/home.js'),
  auth: {
    login: require('routes/auth/login.js'),
    logout: require('routes/auth/logout.js'),
    register: require('routes/auth/register.js')
  }
};

Note that routes.index will be undefined as you would hope.

Specifying Another Directory

You can specify which directory you want to build a tree of (if it isn't the current directory for whatever reason) by passing it as the second parameter. Not specifying the path (requireDirectory(module)) is the equivelant of requireDirectory(module, __dirname):

var requireDirectory = require('require-directory');
module.exports = requireDirectory(module, './some/subdirectory');

For example, in the example in the Usage section we could have avoided creating routes/index.js and instead changed the first lines of app.js to:

var requireDirectory = require('require-directory');
var routes = requireDirectory(module, './routes');

Options

You can pass an options hash to require-directory as the 2nd parameter (or 3rd if you're passing the path to another directory as the 2nd parameter already). Here are the available options:

Whitelisting

Whitelisting (either via RegExp or function) allows you to specify that only certain files be loaded.

var requireDirectory = require('require-directory'),
  whitelist = /onlyinclude.js$/,
  hash = requireDirectory(module, {include: whitelist});

var requireDirectory = require('require-directory'),
  check = function(path){
    if(/onlyinclude.js$/.test(path)){
      return true; // don't include
    }else{
      return false; // go ahead and include
    }
  },
  hash = requireDirectory(module, {include: check});

Blacklisting

Blacklisting (either via RegExp or function) allows you to specify that all but certain files should be loaded.

var requireDirectory = require('require-directory'),
  blacklist = /dontinclude\.js$/,
  hash = requireDirectory(module, {exclude: blacklist});

var requireDirectory = require('require-directory'),
  check = function(path){
    if(/dontinclude\.js$/.test(path)){
      return false; // don't include
    }else{
      return true; // go ahead and include
    }
  },
  hash = requireDirectory(module, {exclude: check});

Visiting Objects As They're Loaded

require-directory takes a function as the visit option that will be called for each module that is added to module.exports.

var requireDirectory = require('require-directory'),
  visitor = function(obj) {
    console.log(obj); // will be called for every module that is loaded
  },
  hash = requireDirectory(module, {visit: visitor});

The visitor can also transform the objects by returning a value:

var requireDirectory = require('require-directory'),
  visitor = function(obj) {
    return obj(new Date());
  },
  hash = requireDirectory(module, {visit: visitor});

Renaming Keys

var requireDirectory = require('require-directory'),
  renamer = function(name) {
    return name.toUpperCase();
  },
  hash = requireDirectory(module, {rename: renamer});

No Recursion

var requireDirectory = require('require-directory'),
  hash = requireDirectory(module, {recurse: false});

Run Unit Tests

$ npm run lint
$ npm test

License

MIT License

Author

Troy Goode ([e-mail])